i18n wrapper and Koa middleware for Lad
Table of Contents
Install
npm:
npm install @ladjs/i18n
yarn:
yarn add @ladjs/i18n
Usage
const I18N = require('@ladjs/i18n');
const phrases = { 'HELLO': 'Hello there!' };
const i18n = new I18N({ phrases });
app.use(i18n.middleware);
app.use(i18n.redirect);
app.listen();
API
i18n.translate(key, locale)
Returns translation for phrase key
with the given locale
.
i18n.middleware(ctx, next)
This middleware uses custom locale detection (in order of priority):
- Check URL (e.g. if
/de
or /de/
then it's a de
locale - as long as de
is a supported locale) - Check the
"locale"
cookie value (or whatever the cookie
option is defined as) - Check
Accept-Language
header
It also exposes the following:
ctx.pathWithoutLocale
- the ctx.path
without the locale in it (this is used by koa-meta)ctx.request
- with all of i18n
API methods (e.g. ctx.request.t
, ctx.request.tn
, ...)ctx.locale
- set to the value of ctx.request.locale
(the current user's locale)ctx.state
- with all of i18n
API methods (e.g. ctx.request.t
, ctx.request.tn
, ...)ctx.state.l
- a shorthand method that accepts a path and returns a localized path (e.g. ctx.state.l('/contact')
will output /en/contact
if the locale is "en")ctx.state.availableLanguages
(Array) - which is useful for adding a dropdown to select from an available languagectx.state.currentLanguage
(String) - the current locale's language in native language using country-language's getLanguage
method.ctx.translate
(Function) - a helper function for calling i18n.api.t
to translate a given phrase by its property key name from the phrases
object option (same as i18n.translate
except it throws a ctx.throw
error using Boom)
If the given locale was not available then it will redirect the user to the detected (or default/fallback) locale.
i18n.redirect(ctx, next)
Inspired by node's language support.
Redirects user with permanent 302
redirect to their detected locale if a valid language was not found for them.
NOTE: As of v1.2.2 we have added a ignoredRedirectGlobs
option you can pass to new I18N({ ... })
which will ignore these paths for locale redirection. This is incredibly useful if you are using authentication providers and the passport
library, e.g. you want to set /auth/github/ok
as the callback URL for GitHub, but a redirect to /en/auth/github/ok
would have occurred, thus causing authentication to fail due to a bad code. In this case, you would set { ignoredRedirectGlobs: [ '/auth/**/*' ] }
or simply [ '/auth/google/ok' ]
. This package uses multimatch internally which supports an Array, therefore you could negate certain paths if needed. See the documentation for multimatch for more insight.
It also sets the cookie locale
for future requests to their detected locale.
This also stores the last_locale
(or whatever you configure the property name to be in the config option lastLocaleField
) for a user via ctx.state.user.save()
.
Options
We use i18n options per https://github.com/mashpie/i18n-node#list-of-all-configuration-options
Default options are as follows and can be overridden:
const i18n = new I18N({
phrases: {},
logger: console,
directory: resolve('locales'),
locales: ['en', 'es', 'zh'],
cookie: 'locale',
indent: ' ',
defaultLocale: 'en',
syncFiles: true,
autoReload: false,
updateFiles: true,
api: {
__: 't',
__n: 'tn',
__l: 'tl',
__h: 'th',
__mf: 'tmf'
},
register: i18n.api,
lastLocaleField: 'last_locale',
ignoredRedirectGlobs: []
});
If you wish to bind logDebugFn
, logWarnFn
, and logErrorFn
per i18n options:
const i18n = new I18N({
logDebugFn: console.log,
logWarnFn: console.log,
logErrorFn: console.log
});
We recommend to use CabinJS for all your logging needs.
For a list of all available locales see i18n-locales.
Contributors
License
MIT © Nick Baugh